/*******************************************************************************
 * Copyright (c) 2008 Jakub Kornas.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the GNU Lesser Public License v2.1
 * which accompanies this distribution, and is available at
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * 
 * Contributors:
 *     Jakub Kornas - initial API and implementation
 *     Sylvain Sicard - integration in FracLite Runtime
 ******************************************************************************/

package org.objectweb.fractal.deployment.local.api;

import org.objectweb.fractal.api.Component;

/**
 * An {@link IModuleComponentFactory} is able to obtain code from a remote
 * {@link IPhysicalPackageRepository} and install it on a local machine on which it
 * executes. Once packages are installed by an {@link IModuleComponentFactory}, their content
 * can be used to create (instantiate) {@link Component}s.
 * 
 * @author <a href="mailto:jakub.kornas@inrialpes.fr">Jakub Kornas
 */
public interface IModuleComponentFactory {

	/**
	 * Installs a package given a {@link IModuleDescriptor}
	 * 
	 * @param packageDescription
	 *            A description of the package to be installed. Implementation
	 *            specific
	 * @return A {@link ModuleComponent} object representing the given
	 *         package installed in the file system. Implementation specific
	 */
	public ModuleComponent install(IModuleDescriptor packageDescription);

	/**
	 * Installs a package and marks it for later use. Marked packages can not be
	 * garbage collected
	 * 
	 * @param packageDescription
	 *            A description of the package to be installed. Implementation
	 *            specific
	 */
	public ModuleComponent installAndMark(
			IModuleDescriptor packageDescription);

	/**
	 * Uninstalls a package. Even marked packages are uninstalled if this method
	 * is called
	 * 
	 * @param packageDescription
	 *            A description of the package to be uninstalled. Implementation
	 *            specific
	 */
	public void uninstall(ModuleComponent componentPackage)
			throws Exception;

	/**
	 * Lists all {@link ModuleComponent}s installed by this
	 * {@link IModuleComponentFactory}
	 * 
	 * @return A table containing the installed packages
	 */
	public ModuleComponent[] getInstalledPackages();

	/**
	 * @return Returns the loaderFactory.
	 * @uml.property name="loaderFactory" default="new model.LoaderFactory()"
	 * @uml.associationEnd multiplicity="(1 1)"
	 *                     inverse="installer:model.LoaderFactory"
	 */
	// public LoaderFactory getLoaderFactory();
	/**
	 * Setter of the property <tt>loaderFactory</tt>
	 * 
	 * @param loaderFactory
	 *            The loaderFactory to set.
	 * @uml.property name="loaderFactory"
	 */
	// public void setLoaderFactory(LoaderFactory loaderFactory);
	/**
	 * @return Returns the packageRepository.
	 * @uml.property name="packageRepository"
	 * @uml.associationEnd multiplicity="(1 -1)"
	 *                     inverse="installer:model.PackageRepository"
	 */
	// public Collection getPackageRepository();
	/**
	 * Setter of the property <tt>packageRepository</tt>
	 * 
	 * @param packageRepository
	 *            The packageRepository to set.
	 * @uml.property name="packageRepository"
	 */
	// public void setPackageRepository(Collection packageRepository);
	// public void registerGarbageCollector(GarbageCollector gc);
}
